Einheit 8 — Deployen und ausführen

Was du nach dieser Einheit weißt: Du bringst geprüften Quelltext als Workflow in die Instanz, löst Ausführungen gezielt aus und verstehst, warum das Ergebnis meistens nicht sofort zurückkommt.

`workflow_deploy` — neu anlegen

{
  "source": "module academy\n\nflow kontaktanfrage { … }",
  "name": "Kurs 6 | Kontaktanfrage aus Freitext",
  "description": "Nimmt einen E-Mail-Text entgegen, extrahiert den Absender per KI und legt ihn in der Kontakt-API an.",
  "project_id": 14
}

Parameter	Pflicht	Hinweis
`source`	ja	Der TowelScript-Quelltext
`name`	nein — aber praktisch immer setzen	Ohne diesen Parameter heißt der Workflow „Workflow"
`description`	nein	Siehe Kurs 5, Einheit 9 — hier gehört hin, was der Workflow tut
`project_id`	nein	Ohne Angabe landet er in „Unassigned"

Die Antwort:

{
  "success": true,
  "workflow_id": 134,
  "workflow_name": "Kurs 6 | Kontaktanfrage aus Freitext",
  "agent_count": 3,
  "message": "Workflow deployed with 3 agents"
}

Prüfe agent_count. Steht dort eine kleinere Zahl als erwartet, ist beim Kompilieren etwas verlorengegangen.

Namen und Beschreibung sind keine Kür

Ein Workflow namens „Workflow" in „Unassigned" ist in zwei Wochen nicht mehr auffindbar. Setze name, description und project_id bei jedem Deploy — das ist dieselbe Disziplin wie in Kurs 5, nur an anderer Stelle.

Was nach dem Deploy noch fehlt

Der Workflow ist vollständig und lauffähig, aber:

Das Canvas-Layout ist unsortiert. TowelScript kennt keine Positionen; die Agents liegen übereinander. Einmal im Designer aufräumen — oder per agent_update mit pos_x/pos_y setzen, wenn du es scripten willst.
Zeitpläne musst du bewusst setzen. Nodes bekommen schedule: "never", wenn nichts angegeben ist.
Zugangsdaten müssen existieren. @secret(…) verweist auf einen Namen. Gibt es ihn nicht, merkst du das erst zur Laufzeit.

`workflow_run` — ausführen

workflow_run erzeugt eine echte Nachricht am Start-Agent und lässt die komplette Kette laufen. Kein Dry-Run.

{
  "workflow_id": 134,
  "input_payload": { "freitext": "Hallo zusammen, …" },
  "timeout_seconds": 25
}

input_payload wird zur message.payload des Eintritts-Agents — dieselbe Regel und dieselbe Fehlerquelle wie bei agent_test_run in Einheit 7: Die Struktur muss der entsprechen, die im Echtbetrieb ankommt.

Wer bekommt die Nachricht?

In dieser Reihenfolge:

Der in entry_agent_id angegebene Agent
sonst der Start-Agent des Workflows
sonst der Agent ohne eingehende Verbindung

entry_agent_id ist nützlich, um einen Abschnitt in der Mitte zu starten, ohne die Stufen davor zu durchlaufen — die Entsprechung zu „Abschnitte isoliert testen" auf Workflow-Ebene.

Synchron oder asynchron

{
  "run_id": "0b1abc97-c4ae-4483-b736-695d3375805f",
  "status": "queued",
  "workflow_id": 134,
  "entry_agent": { "id": 1900, "name": "eingang" },
  "entry_message_id": 29213,
  "output": [],
  "note": "Workflow queued for async execution. Use workflow_logs with the run_id to inspect results."
}

status: "queued" ist der Normalfall. Nur wenn am Workflow synchronous_execution aktiviert ist, wartet das Werkzeug bis zu timeout_seconds und liefert die Ergebnisnachrichten direkt in output.

Leeres output heißt nicht „fehlgeschlagen"

Bei asynchroner Ausführung ist output immer leer. Das Ergebnis holst du dir über die run_id mit workflow_logs oder workflow_messages — siehe Einheit 9.

Die `run_id`

Die run_id ist der Faden durch die gesamte Ausführung. Sie taucht in jeder Nachricht des Laufs als workflow_run_id in der Payload auf:

{
  "freitext": "Hallo zusammen, …",
  "workflow_run_id": "0b1abc97-c4ae-4483-b736-695d3375805f"
}

Damit kannst du selbst bei einem Workflow, der zehnmal am Tag läuft, genau die eine Ausführung nachvollziehen, um die es geht.

📸 Screenshot: [Platzhalter — Run Inspector im Designer mit derselben run_id, die workflow_run zurückgegeben hat]

Die anderen Bauwerkzeuge

`workflow_duplicate`

Kopiert einen Workflow mit neuen GUIDs, erhält Verbindungen und Start-Agent.

{
  "workflow_id": 134,
  "name": "Kontaktanfrage — Variante Vertrieb",
  "project_id": 14,
  "linked_document_mode": "copy"
}

linked_document_mode steuert, was mit verknüpften Dokumenten passiert: copy (Standard), link oder skip.

Typischer Einsatz: eine Variante ausprobieren, ohne das Original anzufassen. Mit link statt copy teilen sich Original und Kopie dieselbe Dokumentation.

`workflow_export`

Liefert den Workflow als portables JSON — zum Sichern, Versionieren oder Importieren in eine andere Umgebung.

{
  "schema_version": 1,
  "name": "Kurs 6 | Kontaktanfrage aus Freitext",
  "guid": "db56b88b-b1da-419b-9688-f33907001b9d",
  "agents": [ … ],
  "links": [ { "source": 0, "receiver": 2 }, { "source": 2, "receiver": 1 } ]
}

Beachte: links referenziert die Positionen im agents-Array, nicht die Namen. Die Reihenfolge im Export entspricht nicht zwangsläufig der Reihenfolge im Fluss.

`workflow_delete`

Löscht Workflow und alle Agents. Endgültig.

{ "success": true, "message": "Workflow \"…\" deleted (had 4 agents)" }

Immer erst exportieren

Es gibt keinen Papierkorb und keine Rückfrage vom Server. Mach workflow_export zur festen Vorstufe jedes Löschens und leg das JSON ab.

Zusammengefasst

Schritt	Werkzeug	Worauf achten
Anlegen	`workflow_deploy`	`name`, `description`, `project_id` setzen; `agent_count` prüfen
Nacharbeiten	Designer / `agent_update`	Layout, Zeitpläne, Zugangsdaten
Ausführen	`workflow_run`	Payload-Struktur; `run_id` merken
Abschnitt starten	`workflow_run` + `entry_agent_id`	Testet Teilketten
Variante bauen	`workflow_duplicate`	`linked_document_mode` bewusst wählen
Sichern	`workflow_export`	Vor jedem Löschen

Weiter: Einheit 9 — Debuggen: Logs, Messages, Re-Emit

workflow_deploy — neu anlegen​

Was nach dem Deploy noch fehlt​

workflow_run — ausführen​

Wer bekommt die Nachricht?​

Synchron oder asynchron​

Die run_id​

Die anderen Bauwerkzeuge​

workflow_duplicate​

workflow_export​

workflow_delete​

Zusammengefasst​